<h1>Go Tips 101</h1>

<div>
Index

<ul class="index summaries" id="tips.html">
<li>
	<a class="index" href="#force-to-use-keyed-struct-literals">How to force package users to use struct composite literals with field names?</a>
</li>
<li>
	<a class="index" href="#make-struct-type-incomparable">How to make a struct type incomparable?</a>
</li>
<li>
	<a class="index" href="#dont-use-assignments-with-expression-dependencies">Don't use value assignments with expressions interacting with each other.</a>
</li>
<li>
	<a class="index" href="#simulate-loop-from-0-to-n">How to simulate <code>for i in 0..N</code> in some other languages?</a>
</li>
<li>
	<a class="index" href="#reset-pointers-for-dead-elements">We should reset the pointers in the element slots which are freed up in all kinds of slice manipulations to avoid memory leaking if we can't make sure if the freed-up element slots will be reused later.</a>
</li>
<li>
	<a class="index" href="#avoid-copying-values-of-some-types">Values of some types in standard packages are not expected to be copied.</a>
</li>
<li>
	<a class="index" href="#memclr">We can use the memclr optimization to reset some contiguous elements in an array or slice.</a>
</li>
<li>
	<a class="index" href="#check-method-existance">How to check if a value has a method without importing the <code>reflect</code> package?</a>
</li>
<li>
	<a class="index" href="#clone-slice-efficiently-and-perfectly">How to efficiently and perfectly clone a slice?</a>
</li>
<li>
	<a class="index" href="#use-three-index-subslice-form">We should use the three-index subslice form at some scenarios.</a>
</li>
<li>
	<a class="index" href="#execute-deferred-calls-earlier">Use anonymous functions to make some deferred function calls be executed earlier.</a>
</li>
<li>
	<a class="index" href="#assert-implementation">Make sure and show a custom defined type implements a specified interface type.</a>
</li>
<li>
	<a class="index" href="#assert-at-compile-time">Some compile-time assertion tricks.</a>
</li>
<li>
	<a class="index" href="#declare-max-int-uint">How to declare maximum int and uint constants?</a>
</li>
<li>
	<a class="index" href="#detect-word-size-at-compile-time">How to detect native word size at compile time?</a>
</li>
<li>
	<a class="index" href="#64bit-alignment-guarantee">How to guarantee that the 64-bit value operated by a 64-bit atomic function call is always 64-bit aligned on 32-bit architectures?</a>
</li>
<li>
	<a class="index" href="#avoid-boxing-large-size-values">Avoid boxing large-size values into interface values.</a>
</li>
<li>
	<a class="index" href="#make-use-of-bce">Make optimizations by using BCE (bounds check elimination).</a>
</li>
</ul>

<p>
</p>

</div>




<div class="summaries-items">

<a class="anchor" id="force-to-use-keyed-struct-literals"></a>
<h3>How to force package users to use struct composite literals with field names?</h3>

<div>

<p>
Package developers can put a non-exported zero-size field in a struct type definition,
so that compilers will forbid package users using composite literals with some
field items but without field names to create values of the struct type.
</p>

An example:

<pre class="line-numbers"><code class="language-go">// foo.go
package foo

type Config struct {
	_    [0]int
	Name string
	Size int
}
</code></pre>

<pre class="line-numbers"><code class="language-go">// main.go
package main

import "foo"

func main() {
	//_ = foo.Config{[0]int{}, "bar", 123} // error
	_ = foo.Config{Name: "bar", Size: 123} // compile ok
}
</code></pre>

<p>
</p>

<p>
Please try not to place the zero-size non-exported field as the last field in the struct,
for <a href="unofficial-faq.html#final-zero-size-field">doing so might enlarge the size of the struct type</a>.
</p>

</div>



<a class="anchor" id="make-struct-type-incomparable"></a>
<h3>How to make a struct type incomparable?</h3>

<div>
Sometimes, we want to avoid a custom struct type being used a map key types,
then we can put a field of a non-exported zero-size incomparable type
in a struct type to make the struct type incomparable.
For example:

<pre class="line-numbers"><code class="language-go">package main

type T struct {
	dummy        [0]func()
	AnotherField int
}

var x map[T]int // compile error: invalid map key type T

func main() {
	var a, b T
	_ = a == b // compile error: invalid operation:
}
</code></pre>

<p>
</p>
</div>



<a class="anchor" id="dont-use-assignments-with-expression-dependencies"></a>
<h3>Don't use value assignments with expressions interacting with each other.</h3>

<div>

<p>
Currently (Go 1.13), there are
<a href="https://github.com/go101/go101/wiki/Some-evaluation-orders-in-multi-value-assignments-are-unspecified">some evaluation orders in a multi-value assignment are unspecified</a> when the expressions involved in the multi-value assignment interact with each other.
So try to split a multi-value assignment into multiple single value assignments
if there are, or you can't make sure whether or not there are, dependencies between the involved expressions.
</p>

In fact, in some bad-written single-value assignments, there are also expression evaluation order ambiguities.
For example, the following program might print <code>[7 0 9]</code>, <code>[0 8 9]</code>,
or <code>[7 8 9]</code>, depending on compiler implementations.

<pre class="line-numbers"><code class="language-go">package main

import "fmt"

var a = &[]int{1, 2, 3}
var i int
func f() int {
	i = 1
	a = &[]int{7, 8, 9}
	return 0
}

func main() {
	// The evaluation order of "a", "i"
	// and "f()" is unspecified.
	(*a)[i] = f()
	fmt.Println(*a)
}
</code></pre>

<p>
</p>

<p>
In other words, a function call in a value assignment may
the evaluation results of the non-function-call expressions in the same assignment.
Please read <a href="evaluation-orders.html">evaluation orders in Go</a> for details.
</p>

</div>



<a class="anchor" id="simulate-loop-from-0-to-n"></a>
<h3>How to simulate <code>for i in 0..N</code> in some other languages?</h3>

<div>

We can range over an array with zero-size element or a nil array pointer to simulate such a loop.
For example:

<pre class="line-numbers"><code class="language-go">package main

import "fmt"

func main() {
	const N = 5

	for i := range [N]struct{}{} {
		fmt.Println(i)
	}
	for i := range [N][0]int{} {
		fmt.Println(i)
	}
	for i := range (*[N]int)(nil) {
		fmt.Println(i)
	}
}
</code></pre>

</div>



<a class="anchor" id="reset-pointers-for-dead-elements"></a>
<h3>We should reset the pointers in the element slots which are freed up in all kinds of slice manipulations to avoid memory leaking if we can't make sure if the freed-up element slots will be reused later.</h3>

<p>
Please read how to <a href="container.html#delete-slice-elements">delete slice elements</a> and <a href="memory-leaking.html#dead-slice-elements">kind-of memory leaking caused by not resetting pointers in dead slice elements</a> for details.
</p>



<a class="anchor" id="avoid-copying-values-of-some-types"></a>
<h3>Values of some types in standard packages are not expected to be copied.</h3>

<div>

<p>
Values of the <code>bytes.Buffer</code> type, <code>strings.Builder</code> type
and the types in the <code>sync</code> standard package are not recommended to be copied.
(They really should not be copied, though it is no problems to copy them
under some specified circumstances.)
</p>

The implementation of <code>strings.Builder</code> will detect
invalid <code>strings.Builder</code> value copies.
Once such a copy is found, panic will occur. For example:

<pre class="line-numbers"><code class="language-go">package main

import "strings"

func main() {
	var b strings.Builder
	b.WriteString("hello ")
	var b2 = b
	b2.WriteString("world!") // panic here
}
</code></pre>

<p>
</p>

Copying values of the types in the <code>sync</code> standard package will be
warned by the <code>go vet</code> command provided in Go SDK.

<pre class="line-numbers"><code class="language-go">// demo.go
package demo

import "sync"

func f(m sync.Mutex) { // warning
	m.Lock()
	defer m.Unlock()
	// do something ...
}
</code></pre>

<pre class="output"><code>$ go vet demo.go
./demo.go:5: f passes lock by value: sync.Mutex
</code></pre>

<p>
</p>

<p>
Copying <code>bytes.Buffer</code> values will never be detected at run time
nor by the <code>go vet</code> command. Just be careful not to do this.
</p>

</div>



<a class="anchor" id="memclr"></a>
<h3>We can use the memclr optimization to reset some contiguous elements in an array or slice.</h3>

<div>

<p>
Please read <a href="container.html#memclr">the <code>memclr</code> optimization</a> for details.
</p>

</div>



<a class="anchor" id="check-method-existance"></a>
<h3>How to check if a value has a method without importing the <code>reflect</code> package?</h3>

<div>

Use the way in the following example.
(Assume the prototype of the method needed to be checked is <code>M(int) string</code>.)

<pre class="line-numbers"><code class="language-go">package main

import "fmt"

type A int
type B int
func (b B) M(x int) string {
	return fmt.Sprint(b, ": ", x)
}

func check(v interface{}) bool {
	_, has := v.(interface{M(int) string})
	return has
}

func main() {
	var a A = 123
	var b B = 789
	fmt.Println(check(a)) // false
	fmt.Println(check(b)) // true
}
</code></pre>

<p>
</p>

</div>



<a class="anchor" id="clone-slice-efficiently-and-perfectly"></a>
<h3>How to efficiently and perfectly clone a slice?</h3>

<div>

<p>
Please read <a href="https://github.com/go101/go101/wiki/How-to-perfectly-clone-a-slice%3F">this wiki article</a>
and <a href="https://github.com/go101/go101/wiki/How-to-efficiently-clone-a-slice%3F">this wiki article</a> for details.
</p>

</div>



<a class="anchor" id="use-three-index-subslice-form"></a>
<h3>We should use the three-index subslice form at some scenarios.</h3>

<div>

Assume a package provides a <code>func NewX(...Option) *X</code> function,
and the implementation of this function will merge the input options with some
internal default options, then the following implementation is not recommended.

<pre class="line-numbers"><code class="language-go">func NewX(opts ...Option) *X {
	options := append(opts, defaultOpts...)
	// Use the merged options to build and return a X.
	// ...
}
</code></pre>

<p>
The reason why the above implementation is not recommended is the
<code>append</code> call may modify the underlying <code>Option</code>
sequence of the argument <code>opts</code>.
For most scenarios, it is not a problem.
But for some special scenarios, it may cause some unexpected results.
</p>

To avoid modifying the underlying <code>Option</code> sequence of
the input argument, we should use the following way instead.

<pre class="line-numbers"><code class="language-go">func NewX(opts ...Option) *X {
	opts = append(opts[:len(opts):len(opts)], defaultOpts...)
	// Use the merged options to build and return a X.
	// ...
}
</code></pre>

<p>
</p>

<p>
On the other hand, for the callers of the <code>NewX</code> function,
it is not a good idea to think and rely on the <code>NewX</code> function
will not modify the underlying elements of the passed slice arguments,
so it is best to pass these arguments with the three-index subslice form.
</p>

<p>
Another scenario at which we should use three-index subslice form is mentioned
in <a href="https://github.com/go101/go101/wiki/The-capacity-of-the-result-byte-%28or-rune%29-slice-of-a-conversion-from-a-string-is-undefined">this wiki article</a>.
</p>

<p>
One drawback of three-index subslice forms is they are some verbose.
In fact, I ever made <a href="https://github.com/golang/go/issues/25638">a proposal</a>
to make it less verbose, but it was declined.
</p>

</div>



<a class="anchor" id="execute-deferred-calls-earlier"></a>
<h3>Use anonymous functions to make some deferred function calls be executed earlier.</h3>

<div>

<p>
Please read <a href="defer-more.html#kind-of-resource-leaking">this article</a> for details.
</p>

</div>



<a class="anchor" id="assert-implementation"></a>
<h3>Make sure and show a custom defined type implements a specified interface type.</h3>

<div>
<p>
We can assign a value of the custom defined type to a variable of type of the specified interface type
to make sure the custom type implements the specified interface type, and more importantly,
to show the custom type is intended to implement which interface types.
Sometimes, writing docs in runnable code is much better than in comments.
</p>

<pre class="line-numbers"><code class="language-go">package myreader

import "io"

type MyReader uint16

func NewMyReader() *MyReader {
	var mr MyReader
	return &mr
}

func (mr *MyReader) Read(data []byte) (int, error) {
	switch len(data) {
	default:
		*mr = MyReader(data[0]) << 8 | MyReader(data[1])
		return 2, nil
	case 2:
		*mr = MyReader(data[0]) << 8 | MyReader(data[1])
	case 1:
		*mr = MyReader(data[0])
	case 0:
	}
	return len(data), io.EOF
}

// Any of the following three lines ensures
// type *MyReader implements io.Reader.
var _ io.Reader = NewMyReader()
var _ io.Reader = (*MyReader)(nil)
func _() {_ = io.Reader(nil).(*MyReader)}
</code></pre>

<p>
</p>
</div>



<a class="anchor" id="assert-at-compile-time"></a>
<h3>Some compile-time assertion tricks.</h3>

<div>
<p>
Besides the above one, there are more compile-time assertion tricks.
</p>

Several ways to guarantee a constant <code>N</code> is not smaller than another constant <code>M</code> at compile time:

<pre class="line-numbers"><code class="language-go">// Any of the following lines can guarantee N >= M
func _(x []int) {_ = x[N-M]}
func _(){_ = []int{N-M: 0}}
func _([N-M]int){}
var _ [N-M]int
const _ uint = N-M
type _ [N-M]int

// If M and N are guaranteed to be positive integers.
var _ uint = N/M - 1
</code></pre>

One more way which is stolen from <a href="https://twitter.com/lukechampine/status/1026695476811390976">@lukechampine</a>.
It makes use of the rule that <a href="container.html#value-literals">duplicate constant keys can't appear in the same composite literal</a>.

<pre class="disable-line-numbers111"><code class="language-go">var _ = map[bool]struct{}{false: struct{}{}, N>=M: struct{}{}}
</code></pre>

The above way looks some verbose but it is more general. It can be used to assert any conditions.
It can be less verbose but needs a little more (negligible) memory:

<pre class="disable-line-numbers111"><code class="language-go">var _ = map[bool]int{false: 0, N>=M: 1}
</code></pre>

<!--p>
NOTE: currently, <a href="https://github.com/golang/go/issues/28104">gccgo 8.2.0 has a bug</a> which allows duplicate constant keys in composite literals.
So this trick doesn't work for gccgo now. This bug will be fixed in a later gccgo version.
</p-->

<p>
</p>

Similarly, ways to assert two integer constants are equal to each other:

<pre class="line-numbers"><code class="language-go">var _ [N-M]int; var _ [M-N]int
type _ [N-M]int; type _ [M-N]int
const _, _ uint = N-M, M-N
func _([N-M]int, [M-N]int) {}

var _ = map[bool]int{false: 0, M==N: 1}

var _ = [1]int{M-N: 0} // the only valid index is 0
var _ = [1]int{}[M-N]  // the only valid index is 0

var _ [N-M]int = [M-N]int{}
</code></pre>

<p>
The last line is also inspired by one of Luke Champine's tweets.
</p>

Ways of how to assert a constant string is not blank:

<pre class="line-numbers"><code class="language-go">type _ [len(aStringConstant)-1]int
var _ = map[bool]int{false: 0, aStringConstant != "": 1}
var _ = aStringConstant[:1]
var _ = aStringConstant[0]
const _ = 1/len(aStringConstant)
</code></pre>

<p>
The last line is stolen from Jan Mercl's <a href="https://groups.google.com/d/msg/golang-nuts/w1-JQMaH7c4/qzBFSPImBgAJ">clever idea</a>.
</p>

Sometimes, to avoid package-level variables consuming too much memory,
we can put assertion code in a function declared with the blank identifier.
For example,

<pre class="line-numbers"><code class="language-go">func _() {
	var _ = map[bool]int{false: 0, N>=M: 1}
	var _ [N-M]int
}
</code></pre>

</div>



<a class="anchor" id="declare-max-int-uint"></a>
<h3>How to declare maximum int and uint constants?</h3>

<div>

<pre class="line-numbers"><code class="language-go">const MaxUint = ^uint(0)
const MaxInt = int(^uint(0) >> 1)
</code></pre>

<p>
</p>

</div>



<a class="anchor" id="detect-word-size-at-compile-time"></a>
<h3>How to detect native word size at compile time?</h3>

<div>

This tip is Go unrelated.

<pre class="line-numbers"><code class="language-go">const Is64bitArch = ^uint(0) >> 63 == 1
const Is32bitArch = ^uint(0) >> 63 == 0
const WordBits = 32 << (^uint(0) >> 63) // 64 or 32
</code></pre>

<p>
</p>

</div>



<a class="anchor" id="64bit-alignment-guarantee"></a>
<h3>How to guarantee that the 64-bit value operated by a 64-bit atomic function call is always 64-bit aligned on 32-bit architectures?</h3>

<div>
Please read <a href="memory-layout.html">Go value memory layouts</a> for details.
</div>



<a class="anchor" id="avoid-boxing-large-size-values"></a>
<h3>Avoid boxing large-size values into interface values.</h3>

<div>
<p>
When a non-interface value is assigned to an interface value, a copy of the non-interface value will be boxed into the interface value.
The copy cost depends on the size of the non-interface value. The larger the size, the higher the copy cost.
So please try to avoid boxing large-size values into interface values.
</p>

In the following example, the costs of the latter two print calls
are much lower than the former two.

<pre class="line-numbers"><code class="language-go">package main

import "fmt"

func main() {
	var a [1000]int

	// This cost of the two lines is high.
	fmt.Println(a)                   // a is copied
	fmt.Printf("Type of a: %T\n", a) // a is copied

	// The cost of the two lines is low.
	fmt.Printf("%v\n", a[:])
	fmt.Println("Type of a:", fmt.Sprintf("%T", &a)[1:])
}
</code></pre>

<p>
</p>

<p>
About value sizes of different types, please read <a href="value-copy-cost.html">value copy costs in Go</a>.
</p>

</div>



<a class="anchor" id="make-use-of-bce"></a>
<h3>Optimize Go code by making use of BCE (bounds check elimination).</h3>

<div>

<p>
Please read <a href="bounds-check-elimination.html">this article</a> to get
what is BCE and how well BCE is supported by the standard Go compiler now.
</p>

Here, another example is provided:

<pre class="line-numbers"><code class="language-go">package main

import (
	"strings"
	"testing"
)

func NumSameBytes_1(x, y string) int {
	if len(x) > len(y) {
		x, y = y, x
	}
	for i := 0; i < len(x); i++ {
		if x[i] != y[i] {
			return i
		}
	}
	return len(x)
}

func NumSameBytes_2(x, y string) int {
	if len(x) > len(y) {
		x, y = y, x
	}
	if len(x) <= len(y) { // more code but more efficient
		for i := 0; i < len(x); i++ {
			if x[i] != y[i] { // bound check eliminated
				return i
			}
		}
	}
	return len(x)
}

var x = strings.Repeat("hello", 100) + " world!"
var y = strings.Repeat("hello", 99) + " world!"

func BenchmarkNumSameBytes_1(b *testing.B) {
	for i := 0; i < b.N; i++ {
		_ = NumSameBytes_1(x, y)
	}
}

func BenchmarkNumSameBytes_2(b *testing.B) {
	for i := 0; i < b.N; i++ {
		_ = NumSameBytes_2(x, y)
	}
}
</code></pre>

In the above example, function <code>NumSameBytes_2</code> is more efficient than function <code>NumSameBytes_1</code>.
The benchmark result:


<pre class="output"><code>BenchmarkNumSameBytes_1-4   	10000000	       669 ns/op
BenchmarkNumSameBytes_2-4   	20000000	       450 ns/op
</code></pre>


<p>
</p>

<p>
Please note, there are many small improvements in each main release of the standard Go compiler (gc).
The trick used in the above example doesn't work for Go SDK versions earlier than 1.11.
And future gc versions may become smarter so that the trick will become unnecessary.
</p>

<!-- https://github.com/golang/go/issues/30945 -->

</div>




</div> <!-- summaries-items -->


<!--

select{}

how to declare a new type which will not has the same underlying type with any already delcared types.
	type T *T

use named returns, better readability

define exported error values as constants, or maybe can make use of declared function values

avoid gc too frequently by allocating a large memory block for a global variable.

try to avoid unnecessary synchronization, for example, make data only be used in one goroutine.
math/rand.NewSource() are faster but not concurrent safe.
but Bytes() method is not fast

try to avoid using large-sized types as
* map key and element types,
* interface dynamic types: don't use string or large size values as error
* channel element types


fmt.Print(v) // values referenced by v escape to heap


sync.Pool, sync.Map

use types without pointer components as container elements would ... the burden of GC.

... GC burdan by reusing values

use {} to shrink scope of identifiers as needed.
use {} to create a nested block to shadow identifiers declared in outer blocks.

intermediate results should be stored out of the benchmark function

select may slow: https://twitter.com/melvinodsa/status/1031434710184939522


try to share Transport for http.Client values. (need a go practice article)
avoid using the http.Get, ..., functions directly.

  http://stackoverflow.com/questions/17948827/reusing-http-connections-in-golang
  So if you create a new Transport for each request,
  it will create new connections each time.
  In this case the solution is to share the one Transport instance between clients.
  http://stackoverflow.com/questions/36688633/how-to-release-http-client-in-go

  Request.Close
  http://craigwickesser.com/2015/01/golang-http-to-many-open-files/
  https://golang.org/pkg/net/http/#Request
        // For client requests, setting this field prevents re-use of
        // TCP connections between requests to the same hosts, as if
        // Transport.DisableKeepAlives were set.

+setting GOMAXPROCS with a value larger than NumCPUs is good for the performance of a program sometimes^M
+https://news.ycombinator.com/item?id=18350362^

simulate subPackages (not work for exported types)
	package foo / import "a.b/foo"
	type SubPkg_ struct{}
	var SubPkg SubPkg_
	func (SubPkg_) FunctionX()
	func (SubPkg_) FunctionY()

	package main
	import "a.b/foo"
	func main() {
		foo.SubPkg.FunctionX()
	}

req.WithContext(context.WithValue(req.Context(), paramsKeyType{}, Params{path, tokens})) is slow
https://github.com/golang/go/issues/28737


<a class="anchor" id="embed-unexported-alias-of-exported-type"></a>
<h3>Embedding an unexported alias of an exported type to avoiding the corresponding anonymous field being modified in user packages.</h3>

	type t = T
	type X struct {
		t
	}
how to embed an exported type as a non-export field?
so that package users can't modify the field.
	type embeddedType = ExportedType

use make() instead of composite literals to initilize map and slice
if the accurate or approiximate number of elements is known.

If the types of some results of a function are identifier,
it would be better to use named results for "code as docs"

manually adjust struct field positions to save memory.


import "sync"
type T struct {
	_ [0]sync.Mutex
}
func main() {
	var t T
	_ = t // go vet: assignment copies lock value to _: main.T contains sync.Mutex
}

the current standard runtime implemention is not friendly when physics memory are not enough.
machine will lang and hang and non-interactive.
Often in devloping, buggy bare loop will cause such cases.
Use "for range [N]struct{}{}" instead.

how to ignore a struct field in comparisons by using reflect.DeepEqual?
* https://github.com/golang/go/issues/29934#issuecomment-475880025
* especially for unepxorted fields


define enum values as non-exported int wrappers.
      type mode struct{m int}
      var (
          Mode0 = mode{0}
          Mode1 = mode{1}
          Mode2 = mode{2}
      )
      to avoid user passing invalid mode values from outside packages.
      If type mode int, then users can pass (Mode2 + 1), which is invalid.

avoid costy copying: dont't range array direct, range its pointer of slices instead.

don't expose package-level data to users.
* bad: var X = 1, good: const X = 1
* bad: var A [3]int, good: func A() [3]int {...}
* bad var S []int, good: func NumElementsOfS() int {} + func ElementOfS(i int) int {}


go sdk 1.13: -trimpath

use //line directive: https://golang.org/src/cmd/compile/doc.go

-->




